This Read Me file documents new features and bug fixes from previous versions of Apple Guide. It also contains late breaking information about the product.
NEW FEATURES IN APPLE GUIDE 2.1
• Apple Guide now supports help access from OpenDoc processes, which involves numerous parts and not a single application process as in the previous help environment. For information on providing guide files for OpenDoc parts, please see the Develop Issue 27 Article titled "Using Apple Guide 2.1, OpenDoc".
• Now supports the ability to access multiple guide files combining the topic areas, index, and look for content across all open guide files.
• There is now CFM 68k glue code present for 68k apps that want to link with the 'AppleGuideGlueLib.68K' shared library code.
•Applications no longer have to build and handle the Help menu if they want their guide files to reside in a folder other than the application's folder. By including a Guide Directory resource (type = 'gdir'; id = -16384) in their application, they can specify a directory for AG to search for guide files other than the application's directory. See 'Guide Directory Resource' topic below.
• Whether an application has guide files or not, Apple Guide was searching through the app's directory 5 different times for guide files. This is now a single search and is much faster. Any guide file information found is cached for performance.
INSTALLATION
• Installation of Apple Guide 2.1 on System 7.5 or later systems.
Simply drag the 'Apple Guide' extension into your System Folder:Extensions folder.
• Installation of Apple Guide 2.1 on pre-System 7.5 systems involves the installation of the following pieces: Apple Guide, '7.0/7.1 Apple Guide Enabler', and AppleScript in the System Folder:Extensions folder.
• Installation of Apple Guide 2.1 on System 7.1.2 PowerPC based Macintosh models will also require the presence of 'AppleScriptLib' in the System Folder:Extensions folder.
Installing OpenDoc files
In order for Apple Guide to interact with OpenDoc it is necessary to place a file called 'AppleGuidePlugIn' in the 'System Folder:Editors:OpenDoc:OpenDoc Shell Plug-Ins:' folder. This plugin is the link for Apple Guide to communicate with OpenDoc processes. The Apple Guide plugin is a 'FAT' version for PowerPC and 68K Macs using OpenDoc 1.0.1 or greater.
Guide files for editors reside in the ':System Folder:Extensions:Global Guide Files:' folder along with the main guide file for OpenDoc itself, called 'OpenDoc Guide'.
KNOWN BUGS
• There is a known bug on PowerBook 520's and 540's that causes a crash when the screen dims. This is an incompatibility between System 7.1.1 and the 7.0/7.1 Apple Guide Enabler. The work around is to not let the screen dim. There are no problems with letting the PowerBook go to sleep. The problem only occurs with System 7.1.1. It does not occur on System 7.5, and System 7.5.1.
• There is problem running the Macintosh Guide file and coaching the non scriptable Finder under 7.0/7.1 systems. This incompatibility will only occur if someone intentionally tries to use this Guide File under these conditions. Macintosh Guide is only for System 7.5 and greater.
• Under System 7.0/7.1 removal of AppleScript extension on 68K based Macintosh’s can cause problems for Guides that contain AppleScripts. Any sequence which tries to execute an AppleScript, with the AppleScript extension missing will result in a crash. A later version Apple Guide will properly report the absence of AppleScript, and not crash.
• Calling any of the AGOpen calls with an FSSpec of a mix-in file instead of the main database fails to load any help. A later version Apple Guide will handle passing in the FSSpec of a mix-in file. The Energy Saver guide on a Macintosh 7500 or a Macintosh 8500 may exhibit this behavior.
• There is an interaction between '7.0/7.1 Apple Guide Enabler' and 'Symantec AntiVirus For Macintosh' (SAM™), which prevents SAM from remembering its state. Version 4.0.6 of SAM fixes the problem. There is a workaround. Rename '7.0/7.1 Apple Guide Enabler' to Load before SAM. This workaround will not work on machines with the Display Enabler installed.
• There is also an interaction between '7.0/7.1 Apple Guide Enabler' and 'Dragging Enabler', which prevents Apple Guide 2.0 from working properly if 'Macintosh Drag and Drop' is installed by the user. The work around is to remove 'Dragging Enabler' from your System Extensions Folder. The '7.0/7.1 Apple Guide Enabler' contains the patches that 'Macintosh Drag and Drop' needs to work properly so 'Dragging Enabler' is not needed anyway.
Multi Guide Files and GuideScript
With the new support for multi process guide files comes an unfortunate side effect that guide authors should know about.
The following commands should not be used in multi-process guide files:
<App Logo>
<App Text>
<Index Instruction>
<Look For Instruction>
<Look For Results Instruction>
<Look For Search Btn Instruction>
<Startup Window>
<Topic Instruction>
<Topic Areas Instruction>
<Balloon Menu Text>
<Howdy>
Note that in multi-process guide files the following exception applies:
<Help Menu> - The specified text will appear as the heading used in the merged access window for that guide file, and not the text used in the Help pull-down menu.
In order to have application-specific items for the above commands, create a main guide file for your application with these command and place it in the Global Guide folder. This will insure that your application logo, text, etc., will appear when the user clicks help on your app. Editor guide files and other multi-process guide files will use the main guide file values for these commands.
Guides saved in their application folder should contain the above commands. If other files from the Global Guide folder are merged into the guide, Apple Guide will still use the original Guide's values, and not merge in the main guide file from the Global Guide folder.
If these commands were to appear in each of the individual guide files, the guide developer might be mislead into thinking that different multi-process guides could have different Howdy texts appearing depending on which parts were currently open. Apple Guide will use the application's main guide to display the above commands.
Guide Directory resource
Apple Guide 2.1 has the ability to search an alternate directory for application guide files as opposed to the familiar searching of the same directory the application is in.
In most cases, it works without code changes to your application. The existence of a 'gdir' resource of resource id '-16384' in your application is enough to indicate to Apple Guide 2.1 where to look for your guide files. If you are currently using the Apple Guide API to populate the Help Menu with your guide files, you will probably want to do a Gestalt check on 'ag_v' and if the result is >= 0x00000210 then you are running Apple Guide 2.1 or later and as long as you have the 'gdir' rsrc you won't need to modify the menu on your own anymore.
The format of the 'gdir' resource; id = -16384 is as follows:
type 'gdir'
{
literal longint kApplicationFolderType = 0,
kSystemFolderType = 'macs',
kControlPanelFolderType = 'ctrl',
kExtensionFolderType = 'extn',
kFontsFolderType = 'font',
kPreferencesFolderType = 'pref';
pstring;
};
resource 'gdir' (-16384)
{
kApplicationFolderType,
"My Guides Are Here"
};
The value of the first is one of the constants used in FindFolder() calls as defined in Folders.h. If that value is NIL then no FindFolder() directory change is completed leaving the search to be based on the application's current directory (e.g. where the app is located).
The value of the second field is the name of the folder to search relative to the result of the above mentioned FindFolder search if one was performed. So for example, if you put 'extn' in the first long value Apple Guide would first go to the ':Extensions:' folder and then look for the directory specified in this second parameter. If no string is specified in this second parameter, then Apple Guide simply begins searching for guide files in the directory specified by the FindFolder result.
Possible Combinations
Using the 'gdir' resource you can get Apple Guide to do the following.
1. Look in a sub-folder relative to the application's directory. How? Specify a folder name in the second field, and 0L in the FindFolder constant value.
2. Look in a FindFolder() directory for guide files. How? Specify a constant in the first field for FindFolder() to use and no string in the second folder name field.
3. Look in a directory inside one of the predefined FindFolder() result directories. How? Specify a constant in the first field for FindFolder and specify a folder name in the second field.
